home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / djgpp / docs / gas / gasp.inf < prev    next >
Encoding:
GNU Info File  |  1994-12-17  |  38.7 KB  |  1,080 lines
  1. This is Info file gasp.info, produced by Makeinfo-1.55 from the input
  2. file ./gasp.texi.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * gasp: (gasp).                     The GNU Assembler Preprocessor
  6. END-INFO-DIR-ENTRY
  7.  
  8.    Copyright (C) 1994 Free Software Foundation, Inc.
  9.  
  10.    Permission is granted to make and distribute verbatim copies of this
  11. manual provided the copyright notice and this permission notice are
  12. preserved on all copies.
  13.  
  14.    Permission is granted to copy and distribute modified versions of
  15. this manual under the conditions for verbatim copying, provided also
  16. that the entire resulting derived work is distributed under the terms
  17. of a permission notice identical to this one.
  18.  
  19.    Permission is granted to copy and distribute translations of this
  20. manual into another language, under the above conditions for modified
  21. versions.
  22.  
  23. 
  24. File: gasp.info,  Node: Top,  Next: Overview,  Prev: (DIR),  Up: (DIR)
  25.  
  26. GASP
  27. ****
  28.  
  29.    GASP is a preprocessor for assembly programs.
  30.  
  31.    This file describes version 1 of GASP.
  32.  
  33.    Steve Chamberlain wrote GASP; Roland Pesch wrote this manual.
  34.  
  35. * Menu:
  36.  
  37. * Overview::                    What is GASP?
  38. * Invoking GASP::               Command line options.
  39. * Commands::                    Preprocessor commands.
  40. * Index::                       Index.
  41.  
  42. 
  43. File: gasp.info,  Node: Overview,  Next: Invoking GASP,  Prev: Top,  Up: Top
  44.  
  45. What is GASP?
  46. *************
  47.  
  48.    The primary purpose of the GNU assembler is to assemble the output of
  49. other programs--notably compilers.  When you have to hand-code
  50. specialized routines in assembly, that means the GNU assembler is an
  51. unfriendly processor: it has no directives for macros, conditionals, or
  52. many other conveniences that you might expect.
  53.  
  54.    In some cases you can simply use the C preprocessor, or a generalized
  55. preprocessor like M4; but this can be awkward, since none of these
  56. things are designed with assembly in mind.
  57.  
  58.    GASP fills this need.  It is expressly designed to provide the
  59. facilities you need with hand-coded assembly code.  Implementing it as a
  60. preprocessor, rather than part of the assembler, allows the maximum
  61. flexibility: you can use it with hand-coded assembly, without paying a
  62. penalty of added complexity in the assembler you use for compiler
  63. output.
  64.  
  65.    Here is a small example to give the flavor of GASP.  This input to
  66. GASP
  67.  
  68.              .MACRO  saveregs from=8 to=14
  69.      count   .ASSIGNA \from
  70.              ! save r\from..r\to
  71.              .AWHILE  \&count LE \to
  72.              mov     r\&count,@-sp
  73.      count   .ASSIGNA  \&count + 1
  74.              .AENDW
  75.              .ENDM
  76.      
  77.              saveregs from=12
  78.      
  79.      bar:    mov     #H'dead+10,r0
  80.      foo     .SDATAC "hello"<10>
  81.              .END
  82.  
  83. generates this assembly program:
  84.  
  85.              ! save r12..r14
  86.              mov     r12,@-sp
  87.              mov     r13,@-sp
  88.              mov     r14,@-sp
  89.      
  90.      bar:    mov     #57005+10,r0
  91.      foo:    .byte   6,104,101,108,108,111,10
  92.  
  93. 
  94. File: gasp.info,  Node: Invoking GASP,  Next: Commands,  Prev: Overview,  Up: Top
  95.  
  96. Command Line Options
  97. ********************
  98.  
  99.    The simplest way to use GASP is to run it as a filter and assemble
  100. its output.  In Unix and its ilk, you can do this, for example:
  101.  
  102.      $ gasp prog.asm | as -o prog.o
  103.  
  104.    Naturally, there are also a few command-line options to allow you to
  105. request variations on this basic theme.  Here is the full set of
  106. possibilities for the GASP command line.
  107.  
  108.      gasp  [ -a | --alternate ]
  109.            [ -c CHAR | --commentchar CHAR ]
  110.            [ -d | --debug ]  [ -h | --help ]
  111.            [ -o OUTFILE | --output OUTFILE ]
  112.            [ -p | --print ]  [ -s | --copysource ]
  113.            [ -u | --unreasonable ]  [ -v | --version ]
  114.            INFILE ...
  115.  
  116. `INFILE ...'
  117.      The input file names.  You must specify at least one input file;
  118.      if you specify more, GASP preprocesses them all, concatenating the
  119.      output in the order you list the INFILE arguments.
  120.  
  121.      Mark the end of each input file with the preprocessor command
  122.      `.END'.  *Note Miscellaneous commands: Other Commands.
  123.  
  124. `-a'
  125. `--alternate'
  126.      Use alternative macro syntax.  *Note Alternate macro syntax:
  127.      Alternate, for a discussion of how this syntax differs from the
  128.      default GASP syntax.
  129.  
  130. `-c 'CHAR''
  131. `--commentchar 'CHAR''
  132.      Use CHAR as the comment character.  The default comment character
  133.      is `!'.  For example, to use a semicolon as the comment character,
  134.      specify `-c ';'' on the GASP command line.  Since assembler
  135.      command characters often have special significance to command
  136.      shells, it is a good idea to quote or escape CHAR when you specify
  137.      a comment character.
  138.  
  139.      For the sake of simplicity, all examples in this manual use the
  140.      default comment character `!'.
  141.  
  142. `-d'
  143. `--debug'
  144.      Show debugging statistics.  In this version of GASP, this option
  145.      produces statistics about the string buffers that GASP allocates
  146.      internally.  For each defined buffersize S, GASP shows the number
  147.      of strings N that it allocated, with a line like this:
  148.  
  149.           strings size S : N
  150.  
  151.      GASP displays these statistics on the standard error stream, when
  152.      done preprocessing.
  153.  
  154. `-h'
  155. `--help'
  156.      Display a summary of the GASP command line options.
  157.  
  158. `-o OUTFILE'
  159. `--output OUTFILE'
  160.      Write the output in a file called OUTFILE.  If you do not use the
  161.      `-o' option, GASP writes its output on the standard output stream.
  162.  
  163. `-p'
  164. `--print'
  165.      Print line numbers.  GASP obeys this option *only* if you also
  166.      specify `-s' to copy source lines to its output.  With `-s -p',
  167.      GASP displays the line number of each source line copied
  168.      (immediately after the comment character at the beginning of the
  169.      line).
  170.  
  171. `-s'
  172. `--copysource'
  173.      Copy the source lines to the output file.  Use this option to see
  174.      the effect of each preprocessor line on the GASP output.  GASP
  175.      places a comment character (`!' by default) at the beginning of
  176.      each source line it copies, so that you can use this option and
  177.      still assemble the result.
  178.  
  179. `-u'
  180. `--unreasonable'
  181.      Bypass "unreasonable expansion" limit.  Since you can define GASP
  182.      macros inside other macro definitions, the preprocessor normally
  183.      includes a sanity check.  If your program requires more than 1,000
  184.      nested expansions, GASP normally exits with an error message.  Use
  185.      this option to turn off this check, allowing unlimited nested
  186.      expansions.
  187.  
  188. `-v'
  189. `--version'
  190.      Display the GASP version number.
  191.  
  192. 
  193. File: gasp.info,  Node: Commands,  Next: Index,  Prev: Invoking GASP,  Up: Top
  194.  
  195. Preprocessor Commands
  196. *********************
  197.  
  198.    GASP commands have a straightforward syntax that fits in well with
  199. assembly conventions.  In general, a command extends for a line, and may
  200. have up to three fields: an optional label, the command itself, and
  201. optional arguments to the command.  You can write commands in upper or
  202. lower case, though this manual shows them in upper case.  *Note Details
  203. of the GASP syntax: Syntax Details, for more information.
  204.  
  205. * Menu:
  206.  
  207. * Conditionals::
  208. * Loops::
  209. * Variables::
  210. * Macros::
  211. * Data::
  212. * Listings::
  213. * Other Commands::
  214. * Syntax Details::
  215. * Alternate::
  216.  
  217. 
  218. File: gasp.info,  Node: Conditionals,  Next: Loops,  Up: Commands
  219.  
  220. Conditional assembly
  221. ====================
  222.  
  223.    The conditional-assembly directives allow you to include or exclude
  224. portions of an assembly depending on how a pair of expressions, or a
  225. pair of strings, compare.
  226.  
  227.    The overall structure of conditionals is familiar from many other
  228. contexts.  `.AIF' marks the start of a conditional, and precedes
  229. assembly for the case when the condition is true.   An optional
  230. `.AELSE' precedes assembly for the converse case, and an `.AENDI' marks
  231. the end of the condition.
  232.  
  233.    You may nest conditionals up to a depth of 100; GASP rejects nesting
  234. beyond that, because it may indicate a bug in your macro structure.
  235.  
  236.    Conditionals are primarily useful inside macro definitions, where you
  237. often need different effects depending on argument values.  *Note
  238. Defining your own directives: Macros, for details about defining macros.
  239.  
  240. `.AIF EXPRA CMP EXPRB'
  241. `.AIF "STRA" CMP "STRB"'
  242.      The governing condition goes on the same line as the `.AIF'
  243.      preprocessor command.  You may compare either two strings, or two
  244.      expressions.
  245.  
  246.      When you compare strings, only two conditional CMP comparison
  247.      operators are available: `EQ' (true if STRA and STRB are
  248.      identical), and `NE' (the opposite).
  249.  
  250.      When you compare two expressions, *both expressions must be
  251.      absolute* (*note Arithmetic expressions in GASP: Expressions.).
  252.      You can use these CMP comparison operators with expressions:
  253.  
  254.     `EQ'
  255.           Are EXPRA and EXPRB equal?  (For strings, are STRA and STRB
  256.           identical?)
  257.  
  258.     `NE'
  259.           Are EXPRA and EXPRB different?  (For strings, are STRA and
  260.           STRB different?
  261.  
  262.     `LT'
  263.           Is EXPRA less than EXPRB?  (Not allowed for strings.)
  264.  
  265.     `LE'
  266.           Is EXPRA less than or equal to EXPRB?  (Not allowed for
  267.           strings.)
  268.  
  269.     `GT'
  270.           Is EXPRA greater than EXPRB?  (Not allowed for strings.)
  271.  
  272.     `GE'
  273.           Is EXPRA greater than or equal to EXPRB?  (Not allowed for
  274.           strings.)
  275.  
  276. `.AELSE'
  277.      Marks the start of assembly code to be included if the condition
  278.      fails.  Optional, and only allowed within a conditional (between
  279.      `.AIF' and `.AENDI').
  280.  
  281. `.AENDI'
  282.      Marks the end of a conditional assembly.
  283.  
  284. 
  285. File: gasp.info,  Node: Loops,  Next: Variables,  Prev: Conditionals,  Up: Commands
  286.  
  287. Repetitive sections of assembly
  288. ===============================
  289.  
  290.    Two preprocessor directives allow you to repeatedly issue copies of
  291. the same block of assembly code.
  292.  
  293. `.AREPEAT AEXP'
  294. `.AENDR'
  295.      If you simply need to repeat the same block of assembly over and
  296.      over a fixed number of times, sandwich one instance of the
  297.      repeated block between `.AREPEAT' and `.AENDR'.  Specify the
  298.      number of copies as AEXP (which must be an absolute expression).
  299.      For example, this repeats two assembly statements three times in
  300.      succession:
  301.  
  302.                   .AREPEAT        3
  303.                   rotcl   r2
  304.                   div1    r0,r1
  305.                   .AENDR
  306.  
  307. `.AWHILE EXPRA CMP EXPRB'
  308. `.AENDW'
  309. `.AWHILE STRA CMP STRB'
  310. `.AENDW'
  311.      To repeat a block of assembly depending on a conditional test,
  312.      rather than repeating it for a specific number of times, use
  313.      `.AWHILE'.  `.AENDW' marks the end of the repeated block.  The
  314.      conditional comparison works exactly the same way as for `.AIF',
  315.      with the same comparison operators (*note Conditional assembly:
  316.      Conditionals.).
  317.  
  318.      Since the terms of the comparison must be absolute expression,
  319.      `.AWHILE' is primarily useful within macros.  *Note Defining your
  320.      own directives: Macros.
  321.  
  322.    You can use the `.EXITM' preprocessor directive to break out of
  323. loops early (as well as to break out of macros).  *Note Defining your
  324. own directives: Macros.
  325.  
  326. 
  327. File: gasp.info,  Node: Variables,  Next: Macros,  Prev: Loops,  Up: Commands
  328.  
  329. Preprocessor variables
  330. ======================
  331.  
  332.    You can use variables in GASP to represent strings, registers, or
  333. the results of expressions.
  334.  
  335.    You must distinguish two kinds of variables:
  336.   1. Variables defined with `.EQU' or `.ASSIGN'.  To evaluate this kind
  337.      of variable in your assembly output, simply mention its name.  For
  338.      example, these two lines define and use a variable `eg':
  339.  
  340.           eg     .EQU   FLIP-64
  341.                  ...
  342.                  mov.l  eg,r0
  343.  
  344.      *Do not use* this kind of variable in conditional expressions or
  345.      while loops; GASP only evaluates these variables when writing
  346.      assembly output.
  347.  
  348.   2. Variables for use during preprocessing.  You can define these with
  349.      `.ASSIGNC' or `.ASSIGNA'.  To evaluate this kind of variable,
  350.      write `\&' before the variable name; for example,
  351.  
  352.           opcit  .ASSIGNA  47
  353.                  ...
  354.                  .AWHILE  \&opcit GT 0
  355.                  ...
  356.                  .AENDW
  357.  
  358.      GASP treats macro arguments almost the same way, but to evaluate
  359.      them you use the prefix `\' rather than `\&'.  *Note Defining your
  360.      own directives: Macros.
  361.  
  362. `PVAR .EQU EXPR'
  363.      Assign preprocessor variable PVAR the value of the expression
  364.      EXPR.  There are no restrictions on redefinition; use `.EQU' with
  365.      the same PVAR as often as you find it convenient.
  366.  
  367. `PVAR .ASSIGN EXPR'
  368.      Almost the same as `.EQU', save that you may not redefine PVAR
  369.      using `.ASSIGN' once it has a value.
  370.  
  371. `PVAR .ASSIGNA AEXPR'
  372.      Define a variable with a numeric value, for use during
  373.      preprocessing.  AEXPR must be an absolute expression.  You can
  374.      redefine variables with `.ASSIGNA' at any time.
  375.  
  376. `PVAR .ASSIGNC "STR"'
  377.      Define a variable with a string value, for use during
  378.      preprocessing.  You can redefine variables with `.ASSIGNC' at any
  379.      time.
  380.  
  381. `PVAR .REG (REGISTER)'
  382.      Use `.REG' to define a variable that represents a register.  In
  383.      particular, REGISTER is *not evaluated* as an expression.  You may
  384.      use `.REG' at will to redefine register variables.
  385.  
  386.    All these directives accept the variable name in the "label"
  387. position, that is at the left margin.  You may specify a colon after
  388. the variable name if you wish; the first example above could have
  389. started `eg:' with the same effect.
  390.  
  391. 
  392. File: gasp.info,  Node: Macros,  Next: Data,  Prev: Variables,  Up: Commands
  393.  
  394. Defining your own directives
  395. ============================
  396.  
  397.    The commands `.MACRO' and `.ENDM' allow you to define macros that
  398. generate assembly output.  You can use these macros with a syntax
  399. similar to built-in GASP or assembler directives.  For example, this
  400. definition specifies a macro `SUM' that adds together a range of
  401. consecutive registers:
  402.  
  403.              .MACRO  SUM FROM=0, TO=9
  404.              ! \FROM \TO
  405.              mov     r\FROM,r10
  406.      COUNT   .ASSIGNA        \FROM+1
  407.              .AWHILE \&COUNT LE \TO
  408.              add     r\&COUNT,r10
  409.      COUNT   .ASSIGNA        \&COUNT+1
  410.              .AENDW
  411.              .ENDM
  412.  
  413. With that definition, `SUM 0,5' generates this assembly output:
  414.  
  415.              ! 0 5
  416.              mov     r0,r10
  417.              add     r1,r10
  418.              add     r2,r10
  419.              add     r3,r10
  420.              add     r4,r10
  421.              add     r5,r10
  422.  
  423. `.MACRO MACNAME'
  424. `.MACRO MACNAME MACARGS ...'
  425.      Begin the definition of a macro called MACNAME.  If your macro
  426.      definition requires arguments, specify their names after the macro
  427.      name, separated by commas or spaces.  You can supply a default
  428.      value for any macro argument by following the name with `=DEFLT'.
  429.      For example, these are all valid `.MACRO' statements:
  430.  
  431.     `.MACRO COMM'
  432.           Begin the definition of a macro called `COMM', which takes no
  433.           arguments.
  434.  
  435.     `.MACRO PLUS1 P, P1'
  436.     `.MACRO PLUS1 P P1'
  437.           Either statement begins the definition of a macro called
  438.           `PLUS1', which takes two arguments; within the macro
  439.           definition, write `\P' or `\P1' to evaluate the arguments.
  440.  
  441.     `.MACRO RESERVE_STR P1=0 P2'
  442.           Begin the definition of a macro called `RESERVE_STR', with two
  443.           arguments.  The first argument has a default value, but not
  444.           the second.  After the definition is complete, you can call
  445.           the macro either as `RESERVE_STR A,B' (with `\P1' evaluating
  446.           to A and `\P2' evaluating to B), or as `RESERVE_STR ,B' (with
  447.           `\P1' evaluating as the default, in this case `0', and `\P2'
  448.           evaluating to B).
  449.  
  450.      When you call a macro, you can specify the argument values either
  451.      by position, or by keyword.  For example, `SUM 9,17' is equivalent
  452.      to `SUM TO=17, FROM=9'.  Macro arguments are preprocessor variables
  453.      similar to the variables you define with `.ASSIGNA' or `.ASSIGNC';
  454.      in particular, you can use them in conditionals or for loop
  455.      control.  (The only difference is the prefix you write to evaluate
  456.      the variable: for a macro argument, write `\ARGNAME', but for a
  457.      preprocessor variable, write `\&VARNAME'.)
  458.  
  459. `NAME .MACRO'
  460. `NAME .MACRO ( MACARGS ... )'
  461.      An alternative form of introducing a macro definition: specify the
  462.      macro name in the label position, and the arguments (if any)
  463.      between parentheses after the name.  Defaulting rules and usage
  464.      work the same way as for the other macro definition syntax.
  465.  
  466. `.ENDM'
  467.      Mark the end of a macro definition.
  468.  
  469. `.EXITM'
  470.      Exit early from the current macro definition, `.AREPEAT' loop, or
  471.      `.AWHILE' loop.
  472.  
  473. `\@'
  474.      GASP maintains a counter of how many macros it has executed in
  475.      this pseudo-variable; you can copy that number to your output with
  476.      `\@', but *only within a macro definition*.
  477.  
  478. `LOCAL NAME [ , ... ]'
  479.      *Warning: `LOCAL' is only available if you select "alternate macro
  480.      syntax" with `-a' or `--alternate'.*  *Note Alternate macro
  481.      syntax: Alternate.
  482.  
  483.      Generate a string replacement for each of the NAME arguments, and
  484.      replace any instances of NAME in each macro expansion.  The
  485.      replacement string is unique in the assembly, and different for
  486.      each separate macro expansion.  `LOCAL' allows you to write macros
  487.      that define symbols, without fear of conflict between separate
  488.      macro expansions.
  489.  
  490. 
  491. File: gasp.info,  Node: Data,  Next: Listings,  Prev: Macros,  Up: Commands
  492.  
  493. Data output
  494. ===========
  495.  
  496.    In assembly code, you often need to specify working areas of memory;
  497. depending on the application, you may want to initialize such memory or
  498. not.  GASP provides preprocessor directives to help you avoid
  499. repetitive coding for both purposes.
  500.  
  501.    You can use labels as usual to mark the data areas.
  502.  
  503. * Menu:
  504.  
  505. * Initialized::
  506. * Uninitialized::
  507.  
  508. 
  509. File: gasp.info,  Node: Initialized,  Next: Uninitialized,  Up: Data
  510.  
  511. Initialized data
  512. ----------------
  513.  
  514.    These are the GASP directives for initialized data, and the standard
  515. GNU assembler directives they expand to:
  516.  
  517. `.DATA EXPR, EXPR, ...'
  518. `.DATA.B EXPR, EXPR, ...'
  519. `.DATA.W EXPR, EXPR, ...'
  520. `.DATA.L EXPR, EXPR, ...'
  521.      Evaluate arithmetic expressions EXPR, and emit the corresponding
  522.      `as' directive (labelled with LAB).  The unqualified `.DATA' emits
  523.      `.long'; `.DATA.B' emits `.byte'; `.DATA.W' emits `.short'; and
  524.      `.DATA.L' emits `.long'.
  525.  
  526.      For example, `foo .DATA 1,2,3' emits `foo: .long 1,2,3'.
  527.  
  528. `.DATAB REPEAT, EXPR'
  529. `.DATAB.B REPEAT, EXPR'
  530. `.DATAB.W REPEAT, EXPR'
  531. `.DATAB.L REPEAT, EXPR'
  532.      Make `as' emit REPEAT copies of the value of the expression EXPR
  533.      (using the `as' directive `.fill').  `.DATAB.B' repeats one-byte
  534.      values; `.DATAB.W' repeats two-byte values; and `.DATAB.L' repeats
  535.      four-byte values.  `.DATAB' without a suffix repeats four-byte
  536.      values, just like `.DATAB.L'.
  537.  
  538.      REPEAT must be an absolute expression with a positive value.
  539.  
  540. `.SDATA "STR" ...'
  541.      String data.  Emits a concatenation of bytes, precisely as you
  542.      specify them (in particular, *nothing is added to mark the end* of
  543.      the string).  *Note String and numeric constants: Constants, for
  544.      details about how to write strings.  `.SDATA' concatenates multiple
  545.      arguments, making it easy to switch between string
  546.      representations.  You can use commas to separate the individual
  547.      arguments for clarity, if you choose.
  548.  
  549. `.SDATAB REPEAT, "STR" ...'
  550.      Repeated string data.  The first argument specifies how many
  551.      copies of the string to emit; the remaining arguments specify the
  552.      string, in the same way as the arguments to `.SDATA'.
  553.  
  554. `.SDATAZ "STR" ...'
  555.      Zero-terminated string data.  Just like `.SDATA', except that
  556.      `.SDATAZ' writes a zero byte at the end of the string.
  557.  
  558. `.SDATAC "STR" ...'
  559.      Count-prefixed string data.  Just like `.SDATA', except that GASP
  560.      precedes the string with a leading one-byte count.  For example,
  561.      `.SDATAC "HI"' generates `.byte 2,72,73'.  Since the count field
  562.      is only one byte, you can only use `.SDATAC' for strings less than
  563.      256 bytes in length.
  564.  
  565. 
  566. File: gasp.info,  Node: Uninitialized,  Prev: Initialized,  Up: Data
  567.  
  568. Uninitialized data
  569. ------------------
  570.  
  571.    Use the `.RES', `.SRES', `.SRESC', and `.SRESZ' directives to
  572. reserve memory and leave it uninitialized.  GASP resolves these
  573. directives to appropriate calls of the GNU `as' `.space' directive.
  574.  
  575. `.RES COUNT'
  576. `.RES.B COUNT'
  577. `.RES.W COUNT'
  578. `.RES.L COUNT'
  579.      Reserve room for COUNT uninitialized elements of data.  The suffix
  580.      specifies the size of each element: `.RES.B' reserves COUNT bytes,
  581.      `.RES.W' reserves COUNT pairs of bytes, and `.RES.L' reserves
  582.      COUNT quartets.  `.RES' without a suffix is equivalent to `.RES.L'.
  583.  
  584. `.SRES COUNT'
  585. `.SRES.B COUNT'
  586. `.SRES.W COUNT'
  587. `.SRES.L COUNT'
  588.      `.SRES' is a synonym for `.RES'.
  589.  
  590. `.SRESC COUNT'
  591. `.SRESC.B COUNT'
  592. `.SRESC.W COUNT'
  593. `.SRESC.L COUNT'
  594.      Like `.SRES', but reserves space for `COUNT+1' elements.
  595.  
  596. `.SRESZ COUNT'
  597. `.SRESZ.B COUNT'
  598. `.SRESZ.W COUNT'
  599. `.SRESZ.L COUNT'
  600.      Like `.SRES', but reserves space for `COUNT+1' elements.
  601.  
  602. 
  603. File: gasp.info,  Node: Listings,  Next: Other Commands,  Prev: Data,  Up: Commands
  604.  
  605. Assembly listing control
  606. ========================
  607.  
  608.    The GASP listing-control directives correspond to related GNU `as'
  609. directives.
  610.  
  611. `.PRINT LIST'
  612. `.PRINT NOLIST'
  613.      Print control.  This directive emits the GNU `as' directive
  614.      `.list' or `.nolist', according to its argument.  *Note `.list':
  615.      (as.info)List, for details on how these directives interact.
  616.  
  617. `.FORM LIN=LN'
  618. `.FORM COL=COLS'
  619. `.FORM LIN=LN COL=COLS'
  620.      Specify the page size for assembly listings: LN represents the
  621.      number of lines, and COLS the number of columns.  You may specify
  622.      either page dimension independently, or both together.  If you do
  623.      not specify the number of lines, GASP assumes 60 lines; if you do
  624.      not specify the number of columns, GASP assumes 132 columns.  (Any
  625.      values you may have specified in previous instances of `.FORM' do
  626.      *not* carry over as defaults.)  Emits the `.psize' assembler
  627.      directive.
  628.  
  629. `.HEADING STRING'
  630.      Specify STRING as the title of your assembly listings.  Emits
  631.      `.title "STRING"'.
  632.  
  633. `.PAGE'
  634.      Force a new page in assembly listings.  Emits `.eject'.
  635.  
  636. 
  637. File: gasp.info,  Node: Other Commands,  Next: Syntax Details,  Prev: Listings,  Up: Commands
  638.  
  639. Miscellaneous commands
  640. ======================
  641.  
  642. `.ALTERNATE'
  643.      Use the alternate macro syntax henceforth in the assembly.  *Note
  644.      Alternate macro syntax: Alternate.
  645.  
  646. `.ORG'
  647.      This command is recognized, but not yet implemented.  GASP
  648.      generates an error message for programs that use `.ORG'.
  649.  
  650. `.RADIX S'
  651.      GASP understands numbers in any of base two, eight, ten, or
  652.      sixteen.  You can encode the base explicitly in any numeric
  653.      constant (*note String and numeric constants: Constants.).  If you
  654.      write numbers without an explicit indication of the base, the most
  655.      recent `.RADIX S' command determines how they are interpreted.  S
  656.      is a single letter, one of the following:
  657.  
  658.     `.RADIX B'
  659.           Base 2.
  660.  
  661.     `.RADIX Q'
  662.           Base 8.
  663.  
  664.     `.RADIX D'
  665.           Base 10.  This is the original default radix.
  666.  
  667.     `.RADIX H'
  668.           Base 16.
  669.  
  670.      You may specify the argument S in lower case (any of `bqdh') with
  671.      the same effects.
  672.  
  673. `.EXPORT NAME'
  674. `.GLOBAL NAME'
  675.      Declare NAME global (emits `.global NAME').  The two directives
  676.      are synonymous.
  677.  
  678. `.PROGRAM'
  679.      No effect: GASP accepts this directive, and silently ignores it.
  680.  
  681. `.END'
  682.      Mark end of each preprocessor file.  GASP issues a warning if it
  683.      reaches end of file without seeing this command.
  684.  
  685. `.INCLUDE "STR"'
  686.      Preprocess the file named by STR, as if its contents appeared
  687.      where the `.INCLUDE' directive does.  GASP imposes a maximum limit
  688.      of 30 stacked include files, as a sanity check.
  689.  
  690. `.ALIGN SIZE'
  691.      Evaluate the absolute expression SIZE, and emit the assembly
  692.      instruction `.align SIZE' using the result.
  693.  
  694. 
  695. File: gasp.info,  Node: Syntax Details,  Next: Alternate,  Prev: Other Commands,  Up: Commands
  696.  
  697. Details of the GASP syntax
  698. ==========================
  699.  
  700.    Since GASP is meant to work with assembly code, its statement syntax
  701. has no surprises for the assembly programmer.
  702.  
  703.    *Whitespace* (blanks or tabs; *not* newline) is partially
  704. significant, in that it delimits up to three fields in a line.  The
  705. amount of whitespace does not matter; you may line up fields in separate
  706. lines if you wish, but GASP does not require that.
  707.  
  708.    The *first field*, an optional "label", must be flush left in a line
  709. (with no leading whitespace) if it appears at all.  You may use a colon
  710. after the label if you wish; GASP neither requires the colon nor
  711. objects to it (but will not include it as part of the label name).
  712.  
  713.    The *second field*, which must appear after some whitespace,
  714. contains a GASP or assembly "directive".
  715.  
  716.    Any *further fields* on a line are "arguments" to the directive; you
  717. can separate them from one another using either commas or whitespace.
  718.  
  719. * Menu:
  720.  
  721. * Markers::
  722. * Constants::
  723. * Symbols::
  724. * Expressions::
  725. * String Builtins::
  726.  
  727. 
  728. File: gasp.info,  Node: Markers,  Next: Constants,  Up: Syntax Details
  729.  
  730. Special syntactic markers
  731. -------------------------
  732.  
  733.    GASP recognizes a few special markers: to delimit comments, to
  734. continue a statement on the next line, to separate symbols from other
  735. characters, and to copy text to the output literally.  (One other
  736. special marker, `\@', works only within macro definitions; *note
  737. Defining your own directives: Macros..)
  738.  
  739.    The trailing part of any GASP source line may be a "comment".  A
  740. comment begins with the first unquoted comment character (`!' by
  741. default), or an escaped or doubled comment character (`\!' or `!!' by
  742. default), and extends to the end of a line.  You can specify what
  743. comment character to use with the `-c' option (*note Command Line
  744. Options: Invoking GASP.).  The two kinds of comment markers lead to
  745. slightly different treatment:
  746.  
  747. `!'
  748.      A single, un-escaped comment character generates an assembly
  749.      comment in the GASP output.  GASP evaluates any preprocessor
  750.      variables (macro arguments, or variables defined with `.ASSIGNA' or
  751.      `.ASSIGNC') present.  For example, a macro that begins like this
  752.  
  753.                   .MACRO  SUM FROM=0, TO=9
  754.                   ! \FROM \TO
  755.  
  756.      issues as the first line of output a comment that records the
  757.      values you used to call the macro.
  758.  
  759. `\!'
  760. `!!'
  761.      Either an escaped comment character, or a double comment character,
  762.      marks a GASP source comment.  GASP does not copy such comments to
  763.      the assembly output.
  764.  
  765.    To *continue a statement* on the next line of the file, begin the
  766. second line with the character `+'.
  767.  
  768.    Occasionally you may want to prevent GASP from preprocessing some
  769. particular bit of text.  To *copy literally* from the GASP source to
  770. its output, place `\(' before the string to copy, and `)' at the end.
  771. For example, write `\(\!)' if you need the characters `\!' in your
  772. assembly output.
  773.  
  774.    To *separate a preprocessor variable* from text to appear
  775. immediately after its value, write a single quote (`'').  For example,
  776. `.SDATA "\P'1"' writes a string built by concatenating the value of `P'
  777. and the digit `1'.  (You cannot achieve this by writing just `\P1',
  778. since `P1' is itself a valid name for a preprocessor variable.)
  779.  
  780. 
  781. File: gasp.info,  Node: Constants,  Next: Symbols,  Prev: Markers,  Up: Syntax Details
  782.  
  783. String and numeric constants
  784. ----------------------------
  785.  
  786.    There are two ways of writing "string constants" in GASP: as literal
  787. text, and by numeric byte value.  Specify a string literal between
  788. double quotes (`"STR"').  Specify an individual numeric byte value as
  789. an absolute expression between angle brackets (`<EXPR>'.  Directives
  790. that output strings allow you to specify any number of either kind of
  791. value, in whatever order is convenient, and concatenate the result.
  792. (Alternate syntax mode introduces a number of alternative string
  793. notations; *note Alternate macro syntax: Alternate..)
  794.  
  795.    You can write "numeric constants" either in a specific base, or in
  796. whatever base is currently selected (either 10, or selected by the most
  797. recent `.RADIX').
  798.  
  799.    To write a number in a *specific base*, use the pattern `S'DDD': a
  800. base specifier character S, followed by a single quote followed by
  801. digits DDD.  The base specifier character matches those you can specify
  802. with `.RADIX': `B' for base 2, `Q' for base 8, `D' for base 10, and `H'
  803. for base 16.  (You can write this character in lower case if you
  804. prefer.)
  805.  
  806. 
  807. File: gasp.info,  Node: Symbols,  Next: Expressions,  Prev: Constants,  Up: Syntax Details
  808.  
  809. Symbols
  810. -------
  811.  
  812.    GASP recognizes symbol names that start with any alphabetic
  813. character, `_', or `$', and continue with any of the same characters or
  814. with digits.  Label names follow the same rules.
  815.  
  816. 
  817. File: gasp.info,  Node: Expressions,  Next: String Builtins,  Prev: Symbols,  Up: Syntax Details
  818.  
  819. Arithmetic expressions in GASP
  820. ------------------------------
  821.  
  822.    There are two kinds of expressions, depending on their result:
  823. "absolute" expressions, which resolve to a constant (that is, they do
  824. not involve any values unknown to GASP), and "relocatable" expressions,
  825. which must reduce to the form
  826.  
  827.      ADDSYM+CONST-SUBSYM
  828.  
  829. where ADDSYM and SUBSYM are assembly symbols of unknown value, and
  830. CONST is a constant.
  831.  
  832.    Arithmetic for GASP expressions follows very similar rules to C.
  833. You can use parentheses to change precedence; otherwise, arithmetic
  834. primitives have decreasing precedence in the order of the following
  835. list.
  836.  
  837.   1. Single-argument `+' (identity), `-' (arithmetic opposite), or `~'
  838.      (bitwise negation).  *The argument must be an absolute expression.*
  839.  
  840.   2. `*' (multiplication) and `/' (division).  *Both arguments must be
  841.      absolute expressions.*
  842.  
  843.   3. `+' (addition) and `-' (subtraction).  *At least one argument must
  844.      be absolute.*
  845.  
  846.   4. `&' (bitwise and).  *Both arguments must be absolute.*
  847.  
  848.   5. `|' (bitwise or) and `~' (bitwise exclusive or; `^' in C).  *Both
  849.      arguments must be absolute.*
  850.  
  851. 
  852. File: gasp.info,  Node: String Builtins,  Prev: Expressions,  Up: Syntax Details
  853.  
  854. String primitives
  855. -----------------
  856.  
  857.    You can use these primitives to manipulate strings (in the argument
  858. field of GASP statements):
  859.  
  860. `.LEN("STR")'
  861.      Calculate the length of string `"STR"', as an absolute expression.
  862.      For example, `.RES.B .LEN("sample")' reserves six bytes of memory.
  863.  
  864. `.INSTR("STRING", "SEG", IX)'
  865.      Search for the first occurrence of SEG after position IX of
  866.      STRING.  For example, `.INSTR("ABCDEFG", "CDE", 0)' evaluates to
  867.      the absolute result `2'.
  868.  
  869.      The result is `-1' if SEG does not occur in STRING after position
  870.      IX.
  871.  
  872. `.SUBSTR("STRING",START,LEN)'
  873.      The substring of STRING beginning at byte number START and
  874.      extending for LEN bytes.
  875.  
  876. 
  877. File: gasp.info,  Node: Alternate,  Prev: Syntax Details,  Up: Commands
  878.  
  879. Alternate macro syntax
  880. ======================
  881.  
  882.    If you specify `-a' or `--alternate' on the GASP command line, the
  883. preprocessor uses somewhat different syntax.  This syntax is
  884. reminiscent of the syntax of Phar Lap macro assembler, but it is *not*
  885. meant to be a full emulation of Phar Lap or similar assemblers.  In
  886. particular, GASP does not support directives such as `DB' and `IRP',
  887. even in alternate syntax mode.
  888.  
  889.    In particular, `-a' (or `--alternate') elicits these differences:
  890.  
  891. *Preprocessor directives*
  892.      You can use GASP preprocessor directives without a leading `.'
  893.      dot.  For example, you can write `SDATA' with the same effect as
  894.      `.SDATA'.
  895.  
  896. *LOCAL*
  897.      One additional directive, `LOCAL', is available.  *Note Defining
  898.      your own directives: Macros, for an explanation of how to use
  899.      `LOCAL'.
  900.  
  901. *String delimiters*
  902.      You can write strings delimited in these other ways besides
  903.      `"STRING"':
  904.  
  905.     `'STRING''
  906.           You can delimit strings with single-quote charaters.
  907.  
  908.     `<STRING>'
  909.           You can delimit strings with matching angle brackets.
  910.  
  911. *single-character string escape*
  912.      To include any single character literally in a string (even if the
  913.      character would otherwise have some special meaning), you can
  914.      prefix the character with `!' (an exclamation mark).  For example,
  915.      you can write `<4.3 !> 5.4!!>' to get the literal text `4.3 >
  916.      5.4!'.
  917.  
  918. *Expression results as strings*
  919.      You can write `%EXPR' to evaluate the expression EXPR and use the
  920.      result as a string.
  921.  
  922. 
  923. File: gasp.info,  Node: Index,  Prev: Commands,  Up: Top
  924.  
  925. Index
  926. *****
  927.  
  928. * Menu:
  929.  
  930. * +:                                    Markers.
  931. * -alternate:                           Invoking GASP.
  932. * -commentchar 'CHAR':                  Invoking GASP.
  933. * -copysource:                          Invoking GASP.
  934. * -debug:                               Invoking GASP.
  935. * -help:                                Invoking GASP.
  936. * -output OUTFILE:                      Invoking GASP.
  937. * -print:                               Invoking GASP.
  938. * -unreasonable:                        Invoking GASP.
  939. * -version:                             Invoking GASP.
  940. * -a:                                   Invoking GASP.
  941. * -c 'CHAR':                            Invoking GASP.
  942. * -d:                                   Invoking GASP.
  943. * -h:                                   Invoking GASP.
  944. * -o OUTFILE:                           Invoking GASP.
  945. * -p:                                   Invoking GASP.
  946. * -s:                                   Invoking GASP.
  947. * -u:                                   Invoking GASP.
  948. * -v:                                   Invoking GASP.
  949. * .AELSE:                               Conditionals.
  950. * .AENDI:                               Conditionals.
  951. * .AENDR:                               Loops.
  952. * .AENDW:                               Loops.
  953. * .AENDW:                               Loops.
  954. * .AIF "STRA" CMP "STRB":               Conditionals.
  955. * .AIF EXPRA CMP EXPRB:                 Conditionals.
  956. * .ALIGN SIZE:                          Other Commands.
  957. * .ALTERNATE:                           Other Commands.
  958. * .AREPEAT AEXP:                        Loops.
  959. * .AWHILE EXPRA CMP EXPRB:              Loops.
  960. * .AWHILE STRA CMP STRB:                Loops.
  961. * .DATA EXPR, EXPR, ...:                Initialized.
  962. * .DATA.B EXPR, EXPR, ...:              Initialized.
  963. * .DATA.L EXPR, EXPR, ...:              Initialized.
  964. * .DATA.W EXPR, EXPR, ...:              Initialized.
  965. * .DATAB REPEAT, EXPR:                  Initialized.
  966. * .DATAB.B REPEAT, EXPR:                Initialized.
  967. * .DATAB.L REPEAT, EXPR:                Initialized.
  968. * .DATAB.W REPEAT, EXPR:                Initialized.
  969. * .END:                                 Other Commands.
  970. * .ENDM:                                Macros.
  971. * .EXITM:                               Macros.
  972. * .EXPORT NAME:                         Other Commands.
  973. * .FORM COL=COLS:                       Listings.
  974. * .FORM LIN=LN:                         Listings.
  975. * .FORM LIN=LN COL=COLS:                Listings.
  976. * .GLOBAL NAME:                         Other Commands.
  977. * .HEADING STRING:                      Listings.
  978. * .INCLUDE "STR":                       Other Commands.
  979. * .INSTR("STRING", "SEG", IX):          String Builtins.
  980. * .LEN("STR"):                          String Builtins.
  981. * .MACRO MACNAME:                       Macros.
  982. * .MACRO MACNAME MACARGS ...:           Macros.
  983. * .ORG:                                 Other Commands.
  984. * .PAGE:                                Listings.
  985. * .PRINT LIST:                          Listings.
  986. * .PRINT NOLIST:                        Listings.
  987. * .PROGRAM:                             Other Commands.
  988. * .RADIX S:                             Other Commands.
  989. * .RES COUNT:                           Uninitialized.
  990. * .RES.B COUNT:                         Uninitialized.
  991. * .RES.L COUNT:                         Uninitialized.
  992. * .RES.W COUNT:                         Uninitialized.
  993. * .SDATA "STR" ...:                     Initialized.
  994. * .SDATAB REPEAT, "STR" ...:            Initialized.
  995. * .SDATAC "STR" ...:                    Initialized.
  996. * .SDATAZ "STR" ...:                    Initialized.
  997. * .SRES COUNT:                          Uninitialized.
  998. * .SRES.B COUNT:                        Uninitialized.
  999. * .SRES.L COUNT:                        Uninitialized.
  1000. * .SRES.W COUNT:                        Uninitialized.
  1001. * .SRESC COUNT:                         Uninitialized.
  1002. * .SRESC.B COUNT:                       Uninitialized.
  1003. * .SRESC.L COUNT:                       Uninitialized.
  1004. * .SRESC.W COUNT:                       Uninitialized.
  1005. * .SRESZ COUNT:                         Uninitialized.
  1006. * .SRESZ.B COUNT:                       Uninitialized.
  1007. * .SRESZ.L COUNT:                       Uninitialized.
  1008. * .SRESZ.W COUNT:                       Uninitialized.
  1009. * .SUBSTR("STRING",START,LEN):          String Builtins.
  1010. * ! default comment char:               Invoking GASP.
  1011. * ; as comment char:                    Invoking GASP.
  1012. * INFILE ...:                           Invoking GASP.
  1013. * NAME .MACRO:                          Macros.
  1014. * NAME .MACRO ( MACARGS ... ):          Macros.
  1015. * PVAR .ASSIGN EXPR:                    Variables.
  1016. * PVAR .ASSIGNA AEXPR:                  Variables.
  1017. * PVAR .ASSIGNC "STR":                  Variables.
  1018. * PVAR .EQU EXPR:                       Variables.
  1019. * PVAR .REG (REGISTER):                 Variables.
  1020. * absolute expressions:                 Expressions.
  1021. * argument fields:                      Syntax Details.
  1022. * avoiding preprocessing:               Markers.
  1023. * bang, as comment:                     Invoking GASP.
  1024. * breaking out of loops:                Loops.
  1025. * comment character, changing:          Invoking GASP.
  1026. * comments:                             Markers.
  1027. * continuation character:               Markers.
  1028. * copying literally to output:          Markers.
  1029. * directive field:                      Syntax Details.
  1030. * EQ:                                   Conditionals.
  1031. * exclamation mark, as comment:         Invoking GASP.
  1032. * fields of GASP source line:           Syntax Details.
  1033. * GE:                                   Conditionals.
  1034. * GT:                                   Conditionals.
  1035. * label field:                          Syntax Details.
  1036. * LE:                                   Conditionals.
  1037. * literal copy to output:               Markers.
  1038. * LOCAL NAME [ , ... ]:                 Macros.
  1039. * loops, breaking out of:               Loops.
  1040. * LT:                                   Conditionals.
  1041. * macros, count executed:               Macros.
  1042. * NE:                                   Conditionals.
  1043. * number of macros executed:            Macros.
  1044. * preprocessing, avoiding:              Markers.
  1045. * relocatable expressions:              Expressions.
  1046. * semicolon, as comment:                Invoking GASP.
  1047. * shriek, as comment:                   Invoking GASP.
  1048. * symbol separator:                     Markers.
  1049. * symbols, separating from text:        Markers.
  1050. * text, separating from symbols:        Markers.
  1051. * whitespace:                           Syntax Details.
  1052. * \@:                                   Macros.
  1053.  
  1054.  
  1055. 
  1056. Tag Table:
  1057. Node: Top822
  1058. Node: Overview1270
  1059. Node: Invoking GASP2936
  1060. Node: Commands6483
  1061. Node: Conditionals7159
  1062. Node: Loops9451
  1063. Node: Variables10976
  1064. Node: Macros13371
  1065. Node: Data17333
  1066. Node: Initialized17781
  1067. Node: Uninitialized20060
  1068. Node: Listings21071
  1069. Node: Other Commands22267
  1070. Node: Syntax Details24019
  1071. Node: Markers25155
  1072. Node: Constants27403
  1073. Node: Symbols28605
  1074. Node: Expressions28901
  1075. Node: String Builtins30133
  1076. Node: Alternate30914
  1077. Node: Index32532
  1078. 
  1079. End Tag Table
  1080.